Is this suggesting that if contentMediaType is present at the top level of the schema that the entire data instance should be decoded with that media type before passing to validation? That would conflict with the expectation by the schema itself that the data instance is a string and that contentSchema should be used for validation of the decoded instance -- if the instance is already decoded to an object, contentSchema will do nothing. I think we should recommend that an explicit media type should be specified instead, which is available for all places that a schema is used (parameters as well as message bodies).

Additionally, we could specify that schema keywords that require a specific type (e.g. uniqueItems, properties) can be used to infer a specific data type for the instance. I also wouldn't mind if we didn't do this, and instead required the user to be explicit with a type keyword, so an implementation doesn't have to enumerate all of the type-specific keywords present in JSON Schema (it's version specific, e.g. an OAD that happened to use the a schema dialect under draft2019-09 would need to include additionalItems -- and asking the OAD parser to also have to parse the $schema keyword is going a little far).

Also, is this suggesting that data deeper within the instance (for example items in an array) need type inference as well, or is this intended only as a mechanism for determining the type of the overall data instance?

If the latter, there is no need to perform schema inspection for an XML document, as surely the media type would be indicating that. The only application I've found in my implementation for needing type inference is for the parameter style and explode features, which require an array or object to operate on and do not use media types.

@karenetheridge

Is this suggesting that if contentMediaType is present at the top level of the schema that the entire data instance should be decoded with that media type before passing to validation?

No. I'll have to go back over this in detail to try to figure out how it seems to be implying that and improve it. I'm trying to cover several scenarios here and I probably muddled them together a bit.

Additionally, we could specify that schema keywords that require a specific type

I spent too much effort ripping a rule somewhat like that out of 3.x (type: array required items in 3.0) to be willing to do such a thing now (and I appreciate that you would rather not do that either). More seriously, the goal here is to strike a balance of allowing some authoring flexibility in arranging schemas without requiring implementors to do too much. Inferring types from other keywords, which can quickly get contradictory when dealing with dynamically typed structures, is definitely over the line into "too much" for me.

and instead required the user to be explicit with a type keyword

I don't want to outright require one in any specific place either. I'd like to make it clear where things definitely MUST work, and make it clear that there are a lot of things beyond that that won't be expected to work. But there might be unexpected configurations that will work fine in practice, or that specific tools support (perhaps already implemented when deciding how to handle the ambiguity in the first place).

Also, is this suggesting that data deeper within the instance (for example items in an array) need type inference as well, or is this intended only as a mechanism for determining the type of the overall data instance?

It's for whatever requirements in the spec need this kind of things. Correlating Encoding Objects with Schema Objects is probably the most obvious and complicated. And then once you've done that, figuring out the default contentType. Other use cases are figuring out the destination type of ambiguous strings (e.g. query parameters).

If the latter, there is no need to perform schema inspection for an XML document, as surely the media type would be indicating that.

No this is the "where data is stored as strings without type information" use case, where it might be unclear how to parse <foo attr="true">42</foo>. Are those the boolean true and the number 42 or the strings "true" and "42" or some combination? That's distinct from the multipart part use case or other embedded media type use case where you might need to figure out a media type that does not have a Media Type Object with parent key- see PR #4744 for this specific use case.

@karenetheridge to make this part more clear:

But there might be unexpected configurations that will work fine in practice

For example, if you set the Encoding Object's contentType explicitly, there's no need to locate any schema information to determine its default. But also I don't want complex rules around "if you don't set contentType explicitly, your schema MUST look like...." Rather, if it is unclear whether tooling can detect the default behavior, authors should heed the limitations in the spec and decide to set contentType explicitly themselves.

Similarly, when parsing query parameters and trying to figure out the type, maybe tools just try parsing them in that type order I give, on the grounds that the precedence is probably right. Basically treating it as an "any" type and guessing. As long as they validate it afterwards, that should be pretty reliable (I say "should" because somewhere there's some schema that could work out either of two ways and was intended to go the other way, but I can't figure out what that would look like off the top of my head).

I don't want to outright require one in any specific place either. I'd like to make it clear where things definitely MUST work, and make it clear that there are a lot of things beyond that that won't be expected to work.

One scenario here where a type keyword is required is for a header parameter -- an incoming value of "blue,black,brown" could be legitimately parsed as a string or an array, and we'd need to look at the schema to know which is expected. If we see "type":"array" at the top level of the schema then we can confidently parse into the array ["blue", "black", "brown"] and at least have a chance of validating against the schema as a whole (whereas leaving it as a string will definitely be invalid).

In my implementation I don't do any of the guessing that you describe (try parsing into one type, see if it's valid, then parse it a different way and try again). The schema gets one crack at trying to validate the data, and if it failed to specify what type was expected, too bad!

It's nice that this is getting into the spec in clear language. When I implemented parameter parsing I was following https://swagger.io/docs/specification/v3_0/serialization/ and tried to reverse-engineer what they were assuming, since these docs are all written from the client-side perspective (constructing an HTTP message from raw data) as opposed to the parsing and deserializing perspective.

The schema gets one crack at trying to validate the data, and if it failed to specify what type was expected, too bad!

There are too many scenarios where it's reasonable not to have a type right there in the inline schema. If nothing else, when there is a $ref. I wrestled a bit with how much to require, but following $ref and allOf seems straightforward enough. But I am open to other requirements. I have just seen plenty of implementations (including one I worked on - not publicly available sadly) that search those and roll up examples or flatten allOfs to make the documentation rendering better. It seemed like a reasonable amount of searching.

I also considered allowing implementations to put some sort of step limit on it, like not following more than X number of $refs, but it's not like that gets any harder the more you do, and figuring out how to count "steps" with both $ref and allOf hurt my brain :-)

One scenario here where a type keyword is required is for a header parameter -- an incoming value of "blue,black,brown" could be legitimately parsed as a string or an array, and we'd need to look at the schema to know which is expected.

This is a really good point as "type": ["array", "string"] would be a problem for that parameter. I think the rules I wrote would end up with it treated as an array, as string is always the type of last resort. But do we want that? Unlike the use cases I was thinking of, this truly could go either way, so we're picking a winner here based on rules I made up as I wrote them.

The one multi-value type use case that I think we MUST (heh) require support for is adding "null" to another type (e.g. "type": ["number", "null"]). If we think the multi-type rules are too complex or too likely to have unexpected behavior, we could just special-case it for one non-"null" type plus "null". I'm really uncertain as to what is best here and would love to hear more opinions.

This is a really good point as "type": ["array", "string"] would be a problem for that parameter. I think the rules I wrote would end up with it treated as an array, as string is always the type of last resort.

That's what I do -- array is selected first if it's possible, then object, then string is the final fallback as the "original" format of the data.

BTW after you created this PR I expanded my type checking to look for allOfs, which it does recursively. It was already following $refs for this (bombing out after a configurable max stack depth value is reached). I pondered adding type inference from seeing array- or object-specific keywords but decided to shelve that for now. But allOf is a quite reasonable addition.

@karenetheridge so do you think we should keep the type precedence list for multi-valued type? Sounds like you were doing something close to this?

Regarding the header parameter, I did some digging and there seem to be three cases:

1. Headers that cannot be list-valued, in which case blue,black,brown need not be quoted and is just a string
2. Headers that can be list-valued in the normal way, where the values can appear on a single line, separated by commas, in which case blue,black,brown is an array of strings but "blue,black,brown" is a string (because of the quotes... "blue","black","brown" would also be an array, with unnecessary but allowed quotes)
3. Set-Cookie, which has to be treated differently from everything else per its own RFC and per RFC9110 (because it can be list-valued, but it also uses commas in unquoted values so you can't use commas as a delimiter on a single line, you have to put it on multiple lines)

well not quite.. there's also minLength and maxLength. But I think I'd be inclined to check the Content-Length header for this instead.

@karenetheridge oh good point, we even say something about maxLength in binary streaming... I'll rework this a bit.

@karenetheridge fixed in the most recent commit.

"format": "binary" would be an ideal signal for this.

That's not a format in 3.1+. the appropriate signal would be "contentMediaType": "application/octet-stream" or similar. But because of how the Encoding Object works, it's all more complicated.

There are many other binary media types, e.g. image/jpeg, where it's not useful to apply a schema to the content and we might want to use a placeholder.

I'm now wondering if we need a signal for "do not bother trying to deserialize this content for the purpose of validation". At present my implementation always applies the appropriate media type deserialization to the content and applies the schema to it (and throws an error if it doesn't know how to process that media type, or if the deserializer encountered an error), but bypassing that might be useful.

@karenetheridge I meant "some binary media type in contentMediaType" more than specifically application/octet-stream, but arguably tacking "or similar" on as I did was not sufficiently clear!

I'm open to better ideas here. Perhaps it is best to remove the placeholder idea as it is pretty squishy and can easily cause problems, and just document the schema search (and break apart) process, which leverages things implementations have to do anyway. We could include a brief note about the possibilities and dangers of using a placeholder instead? idk.

I'm now wondering if we need a signal for "do not bother trying to deserialize this content for the purpose of validation". At present my implementation always applies the appropriate media type deserialization to the content and applies the schema to it (and throws an error if it doesn't know how to process that media type, or if the deserializer encountered an error), but bypassing that might be useful.

I'm not entirely sure what to do with this. I sort-of follow you, but I would not be surprised if you have the only JSON Schema implementation that can handle this at all, and I want to write the requirements for the typical case.

If we say MUST, we can't give an incomplete example list of keywords - we need to spell out exactly which ones are supported.

Instead we could say "..implementations SHOULD search the following for relevant keywords such as ..., and MUST document which keywords are supported."

The MUST for that is at the point of each use. So in some cases you MUST look for type but in otherse you MUST look for properties, etc.... it's not always the same list.

Ok I see what you mean.

@karenetheridge I added some language to clarify this in the most recent commit [EDIT: 2nd-most-recent commit now].

We can also parse booleans from the strings "0", "1", "false", "true". I have often seen query parameters using 0 or 1 as a flag value.

That's basically why string is the last. I'm not sure what to do here and honestly it's a strong argument for saying that the only thing people need to support is type: ["X", "null"] and let everything else be implementation-defined. Because if you have an instance of 0 or the empty string and type: "boolean" it's easy enough to parse it as false, but if you have type: ["boolean", "number"] then how do you know whether 0 is the boolean false or the number 0? I am increasingly inclined to not try to solve this level of type determination. 🤔